<HTML>
<HEAD>
<TITLE>[Chapter 17] 17.2 PrintJob Class</TITLE>
<META NAME="author" CONTENT="John Zukowski">
<META NAME="date" CONTENT="Thu Jul 31 14:58:05 1997">
<META NAME="form" CONTENT="html">
<META NAME="metadata" CONTENT="dublincore.0.1">
<META NAME="objecttype" CONTENT="book part">
<META NAME="otheragent" CONTENT="gmat dbtohtml">
<META NAME="publisher" CONTENT="O'Reilly &amp; Associates, Inc.">
<META NAME="source" CONTENT="SGML">
<META NAME="subject" CONTENT="Java AWT">
<META NAME="title" CONTENT="Java AWT">
<META HTTP-EQUIV="Content-Script-Type" CONTENT="text/javascript">
</HEAD>
<body vlink="#551a8b" alink="#ff0000" text="#000000" bgcolor="#FFFFFF" link="#0000ee">

<DIV CLASS=htmlnav>
<H1><a href='index.htm'><IMG SRC="gifs/smbanner.gif"
     ALT="Java AWT" border=0></a></H1>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch17_01.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><B><FONT FACE="ARIEL,HELVETICA,HELV,SANSERIF" SIZE="-1">Chapter 17<br>Printing</FONT></B></TD>
<td width=172 align=right valign=top><A HREF="ch17_03.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
</table>

&nbsp;
<hr align=left width=515>
</DIV>
<DIV CLASS=sect1>
<h2 CLASS=sect1><A CLASS="TITLE" NAME="JAWT-CH-17-SECT-2">17.2 PrintJob Class</A></h2>

<P CLASS=para>
<A NAME="CH17.PRINT5"></A>The abstract <tt CLASS=literal>PrintJob</tt> class 
provides the basis for the platform-specific printing subclasses. Through 
<tt CLASS=literal>PrintJob</tt>, you have access to 
properties like page size and resolution. 

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JAWT-CH-17-SECT-2.1">Constructor and Pseudo-Constructor</A></h3>

<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public PrintJob () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>PrintJob()</tt> constructor 
is public; however, the class is abstract, so you would never create a <tt CLASS=literal>PrintJob</tt> 
instance directly. </DL>
<P CLASS=para>
Since you can't call the <tt CLASS=literal>PrintJob</tt> 
constructor directly, you need some other way of getting a print job to 
work with. The proper way to get an instance of <tt CLASS=literal>PrintJob</tt> 
is to ask the <tt CLASS=literal>Toolkit</tt>, which 
is described in <A HREF="ch15_01.htm">Chapter 15, <i>Toolkit and Peers</i></A>. The <tt CLASS=literal>getPrintJob()</tt> 
method requires a <tt CLASS=literal>Frame</tt> as 
the first parameter, a <tt CLASS=literal>String</tt> 
as the second parameter, and a <tt CLASS=literal>Properties</tt> set as the third parameter. Here's 
how you might call it: 

<DIV CLASS=screen>
<P>
<PRE>
PrintJob pjob = getToolkit().getPrintJob(aFrame, "Job Title",
                                         (Properties)null);
</PRE>
</DIV>

<P CLASS=para>
The <tt CLASS=literal>Frame</tt> is used to hold a 
print dialog box, asking the user to confirm or cancel the print job. (Whether 
or not you get the print dialog may be platform specific, but your programs 
should always assume that the dialog may appear.) The <tt CLASS=literal>String</tt> 
is the job's title; it will be used to identify the job in the print 
queue and on the job's header page, if there is one. 

<P CLASS=para>
The <tt CLASS=literal>Properties</tt> parameter is 
used to request printing options, like page reversal. The property names, 
and whether the requested properties are honored at all, are platform specific. 
UNIX systems use the following properties:

<DIV CLASS=simplelist>

<P>
<tt CLASS=literal>awt.print.printer</tt><br>
<tt CLASS=literal>awt.print.paperSize</tt><br>
<tt CLASS=literal>awt.print.destination</tt><br>
<tt CLASS=literal>awt.print.orientation</tt><br>
<tt CLASS=literal>awt.print.options</tt><br>
<tt CLASS=literal>awt.print.fileName</tt><br>
<tt CLASS=literal>awt.print.numCopies</tt><br>
</DIV>

<P CLASS=para>
Windows NT/95 ignores the properties sheet. If the properties sheet is <tt CLASS=literal>null</tt>, 
as in the previous example, you get the system's default printing options. 
If the properties sheet is non-<tt CLASS=literal>null</tt>, 
<tt CLASS=literal>getPrintJob()</tt> modifies it to 
show the actual options used to print the job. You can use the modified 
properties sheet to find out what properties are recognized on your system 
and to save a set of printing options for use on a later print job. 

<P CLASS=para>
If you are printing multiple pages, each page should originate from the 
same print job. 

<P CLASS=para>
According to Sun's documentation, <tt CLASS=literal>getPrintJob()</tt> 
ought to return <tt CLASS=literal>null</tt> if the 
user cancels the print job. However, this is a problem. On some platforms 
(notably Windows NT/95), the print dialog box doesn't even appear 
until you call the <tt CLASS=literal>getGraphics()</tt> method. 
In this case, <tt CLASS=literal>getPrintJob()</tt> 
still returns a print job and never returns <tt CLASS=literal>null</tt>. 
If the user cancels the job, <tt CLASS=literal>getGraphics()</tt> 
returns <tt CLASS=literal>null</tt>. 

</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JAWT-CH-17-SECT-2.2">Methods</A></h3>

<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public abstract Graphics getGraphics () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getGraphics()</tt> method returns 
an instance of <tt CLASS=literal>Graphics</tt> that 
also implements <tt CLASS=literal>PrintGraphics</tt>. 
This graphics context can then be used as the parameter to methods like 
<tt CLASS=literal>paint()</tt>, <tt CLASS=literal>print()</tt>, 
<tt CLASS=literal>update()</tt>, or <tt CLASS=literal>printAll()</tt> 
to print a single page. (All of these methods result in calls to <tt CLASS=literal>paint()</tt>; 
in <tt CLASS=literal>paint()</tt>, you draw whatever 
you want to print on the <tt CLASS=literal>Graphics</tt> 
object.) 

<P CLASS=para>
On Windows NT/95 platforms, <tt CLASS=literal>getGraphics()</tt> 
returns <tt CLASS=literal>null</tt> if the user cancels the print job.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public abstract Dimension getPageDimension () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getPageDimension()</tt> method 
returns the dimensions of the page in pixels, as a <tt CLASS=literal>Dimension</tt> 
object. Since <tt CLASS=literal>getGraphics()</tt> 
returns a graphics context only for a single page, it is the programmer's 
responsibility to decide when the current page is full, print the current 
page, and start a new page with a new <tt CLASS=literal>Graphics</tt> 
object. The page size is chosen to roughly represent a screen but has no 
relationship to the page size or orientation. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public abstract int getPageResolution () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getPageResolution()</tt> method 
returns the number of pixels per inch for drawing on the page. It is completely 
unclear what this means, since the number returned has no relationship 
to the printer resolution. It appears to be similar to the screen resolution. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public abstract boolean lastPageFirst () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>lastPageFirst()</tt> method 
lets you know if the user configured the printer to print pages in reverse 
order. If this returns <tt CLASS=literal>true</tt>, 
you need to generate the last page first. If <tt CLASS=literal>false</tt>, 
you should print the first page first. This is relevant only if you are 
trying to print a multipage document. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public abstract void end () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>end()</tt> method terminates 
the print job. This is the last method you should call when printing; it 
does any cleaning up that's necessary. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void finalize () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>finalize()</tt> method is called 
by the garbage collector. In the event you forget to call <tt CLASS=literal>end()</tt>, 
<tt CLASS=literal>finalize()</tt> calls it for you. 
However, it is best to call <tt CLASS=literal>end()</tt> 
as soon as you know you have finished printing; don't rely on <tt CLASS=literal>finalize()</tt>. </DL>
</DIV>

</DIV>


<DIV CLASS=htmlnav>

<P>
<HR align=left width=515>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch17_01.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><a href="index.htm"><img src='gifs/txthome.gif' border=0 alt='Home'></a></td>
<td width=172 align=right valign=top><A HREF="ch17_03.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
<tr>
<td width=172 align=left valign=top>PrintGraphics Interface</td>
<td width=171 align=center valign=top><a href="index/idx_a.htm"><img src='gifs/index.gif' alt='Book Index' border=0></a></td>
<td width=172 align=right valign=top>Component Methods</td>
</tr>
</table>
<hr align=left width=515>

<IMG SRC="gifs/smnavbar.gif" USEMAP="#map" BORDER=0> 
<MAP NAME="map"> 
<AREA SHAPE=RECT COORDS="0,0,108,15" HREF="../javanut/index.htm"
alt="Java in a Nutshell"> 
<AREA SHAPE=RECT COORDS="109,0,200,15" HREF="../langref/index.htm" 
alt="Java Language Reference"> 
<AREA SHAPE=RECT COORDS="203,0,290,15" HREF="../awt/index.htm" 
alt="Java AWT"> 
<AREA SHAPE=RECT COORDS="291,0,419,15" HREF="../fclass/index.htm" 
alt="Java Fundamental Classes"> 
<AREA SHAPE=RECT COORDS="421,0,514,15" HREF="../exp/index.htm" 
alt="Exploring Java"> 
</MAP>
</DIV>

</BODY>
</HTML>
